% -*- coding: utf-8 -*-
% !TEX program = lualatex
\documentclass[oneside]{book}

\input{manual.sty}
\CodeHigh{lite}
\setcounter{chapter}{2}

\begin{document}

% \chapter{Extra Interfaces}
\chapter{附加接口}
\label{chap:extra}

通常，\verb!tblr! 环境能够接收内部和外部参数：

\begin{codehigh}
\begin{tblr}[<outer specs>]{<inner specs>}
  <table body>
\end{tblr}
\end{codehigh}

\textbf{内部参数}是 \verb!tblr! 的 \underline{必选}项中的参数，
它可以包含第\ref{chap:basic}章中描述的新接口。

\textbf{外部参数}是 \verb!tblr! 的 \underline{可选}项中的参数，
多用于跨页长表格(参见第\ref{chap:long}章)。

可以通过\verb!\SetTblrInner! 和 \verb!\SetTblrOuter! 命令分别设置
内部参数和外部参数。

\section{内部参数}

% In addition to new interfaces in Chapter \ref{chap:basic},
% there are several inner specifications which are described in Table~\ref{key:inner}.
除了第\ref{chap:basic}章中的新接口外，
还有表~\ref{key:inner}中所描述的内部参数。

% \begin{spectblr}[
%   caption = {Keys for the Whole Table},
%   label = {key:table},
% ]{}
%   Key & Description and Values & Initial Value \\
%   \K{rulesep} & space between two hlines or vlines & \V{2pt} \\
%   \K{stretch} & stretch ratio for struts added to cell text & \V{1} \\
%   \K{abovesep} & set vertical space above every row & \V{2pt} \\
%   \K{belowsep} & set vertical space below every row & \V{2pt} \\
%   \K{rowsep} & set vertical space above and below every row & \V{2pt} \\
%   \K{leftsep} & set horizontal space to the left of every column & \V{6pt} \\
%   \K{rightsep} & set horizontal space to the right of every column & \V{6pt} \\
%   \K{colsep} & set horizontal space to both sides of every column & \V{6pt} \\
%   \K{hspan} & horizontal span algorithm: \V{default}, \V{even}, or \V{minimal} & \V{default} \\
%   \K{vspan} & vertical span algorithm: \V{default} or \V{even} & \V{default} \\
  % \K{verb} & you need this key to use verb commands & \None \\
  % \K{baseline} & set the baseline of the table & \V{m} \\
% \end{spectblr}
\begin{spectblr}[
  caption = {内部参数键与键值},
  label = {key:inner},
]{}
  键 & 说明与可选键值 & 初始值 \\
  \K{rulesep} & 两条表格横线或竖线间的间距 & \V{2pt} \\
  \K{stretch} & 单元格文本行距拉伸系数 & \V{1} \\
  \K{abovesep} & 每行前的垂直间距 & \V{2pt} \\
  \K{belowsep} & 每行后的垂直间距 & \V{2pt} \\
  \K{rowsep} & 每行前后的垂直间距 & \V{2pt} \\
  \K{leftsep} & 每列左边的水平间距 & \V{6pt} \\
  \K{rightsep} & 每列右边的水平间距 & \V{6pt} \\
  \K{colsep} & 每列左右的水平间距 & \V{6pt} \\
  \K{hspan} & 单元格水平合并算法： \V{default}、 \V{even}或 \V{minimal} & \V{default} \\
  \K{vspan} & 单元格垂直合并算法： \V{default}或 \V{even} & \V{default} \\
  \K{verb} & 是否使用verb命令 & \None \\
  \K{baseline} & 表格的基线 & \V{m} \\
\end{spectblr}

\subsection{双线间距}

% The following example shows that we can replace \verb!\doublerulesep! parameter with \verb!rulesep! key.
以下示例演示了使用 \verb!rulesep! 键替代\verb!\doublerulesep!命令的方法。
\nopagebreak
\begin{demohigh}
\begin{tblr}{
 colspec={||llll||},rowspec={|QQQ|},
 rulesep=4pt,
}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

\subsection{单元格文本的最小支架}

% The following example shows that we can replace \verb!\arraystretch! parameter with \verb!stretch! key.
以下示例演示了使用 \verb!stretch! 键替代 \verb!\arraystretch! 命令的方法。

\begin{demohigh}
\begin{tblr}{hlines,stretch=1.5}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

\subsection{设置所有行列间距}

% The following example uses \verb!rowsep! and \verb!colsep! keys to set padding for all rows and columns.
以下示例演示了使用 \verb!rowsep!键和\verb!colsep!键设置行/列间距的方法。
\nopagebreak
\begin{demohigh}
\SetTblrInner{rowsep=2pt,colsep=2pt}
\begin{tblr}{hlines,vlines}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

\subsection{行/列合并算法}

% With \verb!hspan=default! or \verb!hspan=even!,
% \verb!tabularray! package will compute column widths from span widths.
% But with \verb!hspan=minimal!, it will compute span widths from column widths.
% The following examples show the results from different \verb!hspan! values.
使用\verb!hspan=default! 或 \verb!hspan=even!时，
\verb!Tabularray! 宏包会使用合并宽度计算列宽度。
但是，使用\verb!hspan=minimal!时，则使用列宽度计算合并宽度。
以下示例演示了使用 \verb!hspan! 键不同取值的结果。

\begin{demohigh}
\SetTblrInner{hlines, vlines, hspan=default}
\begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
 111 111 & 222 222 & 333 333 \\
 12 Multi Columns Multi Columns 12 & & 333 \\
 13 Multi Columns Multi Columns Multi Columns 13 & & \\
 111 & 23 Multi Columns Multi Columns 23 & \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\SetTblrInner{hlines, vlines, hspan=even}
\begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
 111 111 & 222 222 & 333 333 \\
 12 Multi Columns Multi Columns 12 & & 333 \\
 13 Multi Columns Multi Columns Multi Columns 13 & & \\
 111 & 23 Multi Columns Multi Columns 23 & \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\SetTblrInner{hlines, vlines, hspan=minimal}
\begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
 111 111 & 222 222 & 333 333 \\
 12 Multi Columns Multi Columns 12 & & 333 \\
 13 Multi Columns Multi Columns Multi Columns 13 & & \\
 111 & 23 Multi Columns Multi Columns 23 & \\
\end{tblr}
\end{demohigh}

% The following examples show the results from different \verb!vspan! values.
以下示例演示了使用 \verb!vspan! 键不同取值的结果。
\nopagebreak
\begin{demohigh}
\SetTblrInner{hlines, vlines, vspan=default}
\begin{tblr}{column{2}={3.25cm}, cell{2}{2}={r=3}{l}}
  Column1 & Column2 \\
  Row1 & Long text that needs multiple lines.
         Long text that needs multiple lines.
         Long text that needs multiple lines. \\
  Row2 & \\
  Row3 & \\
  Row4 & Short text \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\SetTblrInner{hlines, vlines, vspan=even}
\begin{tblr}{column{2}={3.25cm}, cell{2}{2}={r=3}{l}}
  Column1 & Column2 \\
  Row1 & Long text that needs multiple lines.
         Long text that needs multiple lines.
         Long text that needs multiple lines. \\
  Row2 & \\
  Row3 & \\
  Row4 & Short text \\
\end{tblr}
\end{demohigh}

\subsection{使用代码原样输出命令}

使用 \verb!verb! 键，则在单元格文本中可以使用 \verb!\verb! 命令：

\begin{demohigh}
\begin{tblr}{hlines,verb}
  20 & 30 & \verb!\hello{world}!40 \\
  50 & \verb!\hello!60 & 70 \\
\end{tblr}
\end{demohigh}

\subsection{设置表格基线}

使用 \verb!baseline! 键，可以设置表格的基线。
\verb!baseline! 的取值有：

\begin{center}
\begin{tblr}{width=0.6\textwidth,colspec={cX[l]},hlines}
  \V{t}    & 顶端对齐 \\
  \V{T}    & 首行对齐 \\
  \V{m}    & 垂直居中对齐，初始值 \\
  \V{b}    & 底端对齐 \\
  \V{B}    & 最后一行对齐 \\
  \V{<n>}  & 按第\V{<n>}行对齐 (n是正整数) \\
\end{tblr}
\end{center}

如果在第一行前没有 hline，则 \V{t} 或 \V{T}的作用相同。
但如果第一行前有1个或多个hlines，则结果不同。

\begin{demohigh}
Baseline\begin{tblr}{hlines,baseline=t}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}Baseline
\end{demohigh}

\begin{demohigh}
Baseline\begin{tblr}{hlines,baseline=T}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}Baseline
\end{demohigh}

\verb!b!和 \verb!B! 的区别与 \verb!t! 和 \verb!T!的区别类似。
实质上，\verb!T! 和 \verb!B! 是目前废弃的\verb!\firsthline! 
和 \verb!\lasthline!命令的替代操作。

\section{外部参数}

除了第 \ref{chap:long} 章中说明的参数外，
表~\ref{key:outer}给出了其它外部参数。

\begin{spectblr}[
  caption = {外部参数键和键值},
  label = {key:outer},
]{}
  键 & 说明与可选键值 & 初始值 \\
  \K{baseline} & 设置表格基线 & \V{m} \\
  \K{long} & 更改表格为跨页长表格(longtblr) & \None \\
  \K{tall} & 更改表格为浮动长表格(talltblr) & \None \\
  \K{expand} & 表格内容提前展开宏 & \None \\
\end{spectblr}

\subsection{设置表格基线的另一种方式}

注意，可以在内部参数或外部参数中使用\K{baseline}键，
这两种方式做的是同一件事，但是稍有区别，
如果使用外部参数，则\verb!baseline=t/T/m/b/B!中可以省略键名，
仅使用键值即可。

\begin{demohigh}
Baseline\begin{tblr}[m]{hlines}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}Baseline
\end{demohigh}

\subsection{跨页长表格(longtblr)和浮动长表格(talltblr)}

可以通过在外部参数中设置\K{long}将表格转换为跨页长表格(longtblr)，
或设置\K{tall}将其转换为浮动长表格(talltblr) (参见第~\ref{chap:long}章)。
因此，如下两个表格的结果是一样的：

\begin{codehigh}
\begin{longtblr}{lcr}
  Alpha & Beta & Gamma
\end{longtblr}
\begin{tblr}[long]{lcr}
  Alpha & Beta & Gamma
\end{tblr}
\end{codehigh}

% \section{Expand Macros First}
\section{表格内容宏的提前展开}

% \verb!Tabularray! need to see every \verb!&! and \verb!\\! when splitting the table body
% with \verb!l3regex!. And you can not put cell text inside any table command defined with
% \verb!\NewTableCommand!. But you could use outer specification \verb!expand! to make \verb!tabularray!
% expand every occurrence of a specified macro \underline{once} before splitting the table body.
% The macro \underline{can not} be defined with \verb!\NewDocumentCommand! or
% \verb!\NewExpandableDocumentCommand!, and \underline{can not} have optional argument.
\verb!Tabularray! 宏包使用\verb!l3regex!解析表格内容，
因此，需要知道表格内容中的每一个 \verb!&! 和 \verb!\\! 符号。
所以，不能将表格内容放在任何由 \verb!\NewTableCommand! 命令定义的表格命令中。
但是，可以使用 \verb!expand! 键为 \verb!Tabularray! 宏包指定在解析表格内容之前
\underline{一次}性展开包含表格内容的宏。
注意，该宏\underline{不可以}使用 \verb!\NewDocumentCommand! 或
\verb!\NewExpandableDocumentCommand!
命令定义，并且\underline{不能}有可选参数。

\begin{demohigh}
\def\tblrbody{
 \hline
  20 & 30 & 40 \\
  50 & 60 & 70 \\
 \hline
}
\begin{tblr}[expand=\tblrbody]{ccc}
 \hline
  AA & BB & CC \\
  \tblrbody
  DD & EE & FF \\
  \tblrbody
  GG & HH & II \\
 \hline
\end{tblr}
\end{demohigh}

% With this \verb!expand! option, you can also use \verb!environ! package
% to define a new environment based on \verb!tblr! environment:
% 通过 \verb!expand! 选项，可以利用 \verb!environ! 宏包
% 定义基于 \verb!tblr! 环境的新环境：
%
%
% \begin{demohigh}
% \NewEnviron{fancytblr}{
%  Before Text
%  \begin{tblr}[expand=\BODY]{hlines}
%    \BODY
%  \end{tblr}
%  After Text
% }
% \begin{fancytblr}
%   One   & Two   & Three \\
%   Four  & Five  & Six   \\
%   Seven & Eight & Nine  \\
% \end{fancytblr}
% \end{demohigh}

% \section{Default Specifications}
\section{参数默认值}

% \verb!Tabularray! package provides \verb!\SetTblrInner! and \verb!\SetTblrOuter! commands
% for you to change the default inner and outer specifications of tables.
\verb!Tabularray! 宏包提供了 \verb!\SetTblrInner! 和 \verb!\SetTblrOuter! 两个命令，
这两个命令用于设置表格内部参数和外部参数默认值。

% In the below example, the first line draws all hlines and vlines for all tables created afterwards,
% while the second line makes all tables created afterwards vertically align at bottom.
以下示例中，第一行代码用于设置此后所有表格都绘制表格横线和竖线，
第二行代码用于设置此后所有表格的垂直对齐方式为底端基线对齐。

\begin{codehigh}
\SetTblrInner{hlines,vlines}
\SetTblrOuter{baseline=B}
\end{codehigh}

\section{定义新tabularray环境}

% You can define new \verb!tabularray! environments using \verb!\NewTblrEnviron! command:
可以使用 \verb!\NewTblrEnviron! 命令定义新 \verb!tabularray! 环境：

\begin{demohigh}
\NewTblrEnviron{mytblr}
\SetTblrInner[mytblr]{hlines,vlines}
\SetTblrOuter[mytblr]{baseline=B}
Text \begin{mytblr}{cccc}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{mytblr} Text
\end{demohigh}

% If not giving the optional argument to \verb!\SetTblrInner! or \verb!\SetTblrOuter! command,
% we set the default specifications for \verb!tblr! environment.
% And different tabularray environments could have different default specifications.
如果在 \verb!\SetTblrInner! 或 \verb!\SetTblrOuter! 命令中未指定可选参数，
则使用 \verb!tblr! 环境的默认参数。
因此，不同 \verb!Tabularray! 环境可以具有不同的默认参数。

\section{定义新通用环境}

使用 \verb!\NewDocumentEnvironment! 命令的 \verb!+b! 类型参数，
可以定义基于 \verb!tblr! 环境的新的通用环境
(注意在最后有一对额外的大括号):

\NewDocumentEnvironment{fancytblr}{+b}{
  Before Text
  \begin{tblr}{hlines}
    #1
  \end{tblr}
  After Text
}{}
\begin{codehigh}
\NewDocumentEnvironment{fancytblr}{+b}{
  Before Text
  \begin{tblr}{hlines}
    #1
  \end{tblr}
  After Text
}{}
\end{codehigh}
\begin{demohigh}
\begin{fancytblr}
  One   & Two   & Three \\
  Four  & Five  & Six   \\
  Seven & Eight & Nine  \\
\end{fancytblr}
\end{demohigh}

% \section{New Table Commands}
\section{定义新表格命令}

% All commands which change the specifications of tables \textcolor{red3}{must} be defined with \verb!\NewTableCommand!.
% The following example demonstrates how to define a new table command:
\textcolor{red3}{必须} 使用 \verb!\NewTableCommand! 命令定义所有用于改变表格内容样式的命令 。
下面的示例演示了如何定义一个新的表格命令：

\begin{demohigh}
\NewTableCommand\myhline{\hline[0.1em,red5]}
\begin{tblr}{llll}
\myhline
 Alpha   & Beta  & Gamma   & Delta \\
 Epsilon & Zeta  & Eta     & Theta \\
 Iota    & Kappa & Lambda  & Mu    \\
\myhline
\end{tblr}
\end{demohigh}

\section{寄(odd)/偶(even)选择器}

从2022A版开始，\verb!odd! 和 \verb!even! 子区域选择器可以接受一个可选参数，
用于指定子区域的起始和终止索引值。

\begin{demohigh}
\begin{tblr}{
  cell{odd}{1} = {red9},
  cell{odd[4]}{2} = {green9},
  cell{odd[3-X]}{3} = {blue9},
}
  Head   & Head    & Head   \\
  Talk A & Place A & Date A \\
  Talk B & Place B & Date B \\
  Talk C & Place C & Date C \\
  Talk D & Place D & Date D \\
  Talk E & Place E & Date E \\
  Talk F & Place F & Date F \\
  Talk G & Place G & Date G \\
  Talk H & Place H & Date H \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{
  cell{even}{1} = {yellow9},
  cell{even[4]}{2} = {cyan9},
  cell{even[3-X]}{3} = {purple9},
}
  Head   & Head    & Head   \\
  Talk A & Place A & Date A \\
  Talk B & Place B & Date B \\
  Talk C & Place C & Date C \\
  Talk D & Place D & Date D \\
  Talk E & Place E & Date E \\
  Talk F & Place F & Date F \\
  Talk G & Place G & Date G \\
  Talk H & Place H & Date H \\
\end{tblr}
\end{demohigh}

% \section{Counters and Lengths}
\section{计数器和长度}

% Counters \verb!rownum!, \verb!colnum!, \verb!rowcount!, \verb!colcount! can be used in cell text:
可以在单元格中使用\verb!rownum!、 \verb!colnum!、 \verb!rowcount!和 \verb!colcount!  计数器：
\nopagebreak
\begin{demohigh}
\begin{tblr}{hlines}
 Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] \\
 Row=\arabic{rowcount}, Col=\arabic{colcount} &
 Row=\arabic{rowcount}, Col=\arabic{colcount} &
 Row=\arabic{rowcount}, Col=\arabic{colcount} &
 Row=\arabic{rowcount}, Col=\arabic{colcount} \\
 Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] \\
\end{tblr}
\end{demohigh}

% Also, lengths \verb!\leftsep!, \verb!\rightsep!, \verb!\abovesep!, \verb!\belowsep! can be used in cell text.
也可以在单元格文本中也可以使用
\verb!\leftsep!、 \verb!\rightsep!、 \verb!\abovesep!和 \verb!\belowsep!长度。

% \section{Tracing Tabularray}
\section{跟踪Tabularray}

% To trace internal data behind \verb!tblr! environment, you can use \verb!\SetTblrTracing! command.
% For example, \verb!\SetTblrTracing{all}! will turn on all tracings,
% and \verb!\SetTblrTracing{none}! will turn off all tracings.
% \verb!\SetTblrTracing{+row,+column}! will only tracing row and column data.
% All tracing messages will be written to the log files.
可使用 \verb!\SetTblrTracing! 命令跟踪 \verb!tblr! 的内部数据流。
例如，\verb!\SetTblrTracing{all}! 用于打开所有跟踪，
\verb!\SetTblrTracing{none}! 用于关闭所有跟踪。
而\verb!\SetTblrTracing{+row,+column}! 仅跟踪指定的行和列的数据流。
所有的跟踪结果都将写入log文件。

\end{document}
